/* ===========================================================
 * JFreeChart : a free chart library for the Java(tm) platform
 * ===========================================================
 *
 * (C) Copyright 2000-2009, by Object Refinery Limited and Contributors.
 *
 * Project Info:  http://www.jfree.org/jfreechart/index.html
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
 * USA.
 *
 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
 * in the United States and other countries.]
 *
 * -----------------
 * CategoryAxis.java
 * -----------------
 * (C) Copyright 2000-2009, by Object Refinery Limited and Contributors.
 *
 * Original Author:  David Gilbert;
 * Contributor(s):   Pady Srinivasan (patch 1217634);
 *                   Peter Kolb (patches 2497611 and 2603321);
 *
 * Changes
 * -------
 * 21-Aug-2001 : Added standard header. Fixed DOS encoding problem (DG);
 * 18-Sep-2001 : Updated header (DG);
 * 04-Dec-2001 : Changed constructors to protected, and tidied up default
 *               values (DG);
 * 19-Apr-2002 : Updated import statements (DG);
 * 05-Sep-2002 : Updated constructor for changes in Axis class (DG);
 * 06-Nov-2002 : Moved margins from the CategoryPlot class (DG);
 * 08-Nov-2002 : Moved to new package com.jrefinery.chart.axis (DG);
 * 22-Jan-2002 : Removed monolithic constructor (DG);
 * 26-Mar-2003 : Implemented Serializable (DG);
 * 09-May-2003 : Merged HorizontalCategoryAxis and VerticalCategoryAxis into
 *               this class (DG);
 * 13-Aug-2003 : Implemented Cloneable (DG);
 * 29-Oct-2003 : Added workaround for font alignment in PDF output (DG);
 * 05-Nov-2003 : Fixed serialization bug (DG);
 * 26-Nov-2003 : Added category label offset (DG);
 * 06-Jan-2004 : Moved axis line attributes to Axis class, rationalised
 *               category label position attributes (DG);
 * 07-Jan-2004 : Added new implementation for linewrapping of category
 *               labels (DG);
 * 17-Feb-2004 : Moved deprecated code to bottom of source file (DG);
 * 10-Mar-2004 : Changed Dimension --> Dimension2D in text classes (DG);
 * 16-Mar-2004 : Added support for tooltips on category labels (DG);
 * 01-Apr-2004 : Changed java.awt.geom.Dimension2D to org.jfree.ui.Size2D
 *               because of JDK bug 4976448 which persists on JDK 1.3.1 (DG);
 * 03-Sep-2004 : Added 'maxCategoryLabelLines' attribute (DG);
 * 04-Oct-2004 : Renamed ShapeUtils --> ShapeUtilities (DG);
 * 11-Jan-2005 : Removed deprecated methods in preparation for 1.0.0
 *               release (DG);
 * 21-Jan-2005 : Modified return type for RectangleAnchor.coordinates()
 *               method (DG);
 * 21-Apr-2005 : Replaced Insets with RectangleInsets (DG);
 * 26-Apr-2005 : Removed LOGGER (DG);
 * 08-Jun-2005 : Fixed bug in axis layout (DG);
 * 22-Nov-2005 : Added a method to access the tool tip text for a category
 *               label (DG);
 * 23-Nov-2005 : Added per-category font and paint options - see patch
 *               1217634 (DG);
 * ------------- JFreeChart 1.0.x ---------------------------------------------
 * 11-Jan-2006 : Fixed null pointer exception in drawCategoryLabels - see bug
 *               1403043 (DG);
 * 18-Aug-2006 : Fix for bug drawing category labels, thanks to Adriaan
 *               Joubert (1277726) (DG);
 * 02-Oct-2006 : Updated category label entity (DG);
 * 30-Oct-2006 : Updated refreshTicks() method to account for possibility of
 *               multiple domain axes (DG);
 * 07-Mar-2007 : Fixed bug in axis label positioning (DG);
 * 27-Sep-2007 : Added getCategorySeriesMiddle() method (DG);
 * 21-Nov-2007 : Fixed performance bug noted by FindBugs in the
 *               equalPaintMaps() method (DG);
 * 23-Apr-2008 : Fixed bug 1942059, bad use of insets in
 *               calculateTextBlockWidth() (DG);
 * 26-Jun-2008 : Added new getCategoryMiddle() method (DG);
 * 27-Oct-2008 : Set font on Graphics2D when creating category labels (DG);
 * 14-Jan-2009 : Added new variant of getCategorySeriesMiddle() to make it
 *               simpler for renderers with hidden series (PK);
 * 19-Mar-2009 : Added entity support - see patch 2603321 by Peter Kolb (DG);
 * 16-Apr-2009 : Added tick mark drawing (DG);
 *
 */

package net.droidsolutions.droidcharts.core.axis;

import java.io.Serializable;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import net.droidsolutions.droidcharts.awt.Font;
import net.droidsolutions.droidcharts.awt.Line2D;
import net.droidsolutions.droidcharts.awt.Point2D;
import net.droidsolutions.droidcharts.awt.Rectangle2D;
import net.droidsolutions.droidcharts.awt.Shape;
import net.droidsolutions.droidcharts.common.RectangleAnchor;
import net.droidsolutions.droidcharts.common.RectangleEdge;
import net.droidsolutions.droidcharts.common.RectangleInsets;
import net.droidsolutions.droidcharts.common.ShapeUtilities;
import net.droidsolutions.droidcharts.common.Size2D;
import net.droidsolutions.droidcharts.core.data.CategoryDataset;
import net.droidsolutions.droidcharts.core.entity.CategoryLabelEntity;
import net.droidsolutions.droidcharts.core.entity.EntityCollection;
import net.droidsolutions.droidcharts.core.plot.CategoryPlot;
import net.droidsolutions.droidcharts.core.plot.Plot;
import net.droidsolutions.droidcharts.core.plot.PlotRenderingInfo;
import net.droidsolutions.droidcharts.core.text.G2TextMeasurer;
import net.droidsolutions.droidcharts.core.text.TextBlock;
import net.droidsolutions.droidcharts.core.text.TextUtilities;
import android.graphics.Canvas;
import android.graphics.Paint;

/**
 * An axis that displays categories.
 */
public class CategoryAxis extends Axis implements Cloneable, Serializable {

	/** For serialization. */
	private static final long serialVersionUID = 5886554608114265863L;

	/**
	 * The default margin for the axis (used for both lower and upper margins).
	 */
	public static final double DEFAULT_AXIS_MARGIN = 0.05;

	/**
	 * The default margin between categories (a percentage of the overall axis
	 * length).
	 */
	public static final double DEFAULT_CATEGORY_MARGIN = 0.20;

	/** The amount of space reserved at the start of the axis. */
	private double lowerMargin;

	/** The amount of space reserved at the end of the axis. */
	private double upperMargin;

	/** The amount of space reserved between categories. */
	private double categoryMargin;

	/** The maximum number of lines for category labels. */
	private int maximumCategoryLabelLines;

	/**
	 * A ratio that is multiplied by the width of one category to determine the
	 * maximum label width.
	 */
	private float maximumCategoryLabelWidthRatio;

	/** The category label offset. */
	private int categoryLabelPositionOffset;

	/**
	 * A structure defining the category label positions for each axis location.
	 */
	private CategoryLabelPositions categoryLabelPositions;

	/** Storage for tick label font overrides (if any). */
	private Map tickLabelFontMap;

	/** Storage for tick label paint overrides (if any). */
	private transient Map tickLabelPaintMap;

	/** Storage for the category label tooltips (if any). */
	private Map categoryLabelToolTips;

	/**
	 * Creates a new category axis with no label.
	 */
	public CategoryAxis() {
		this(null);
	}

	/**
	 * Constructs a category axis, using default values where necessary.
	 * 
	 * @param label
	 *            the axis label (<code>null</code> permitted).
	 */
	public CategoryAxis(String label) {

		super(label);

		this.lowerMargin = DEFAULT_AXIS_MARGIN;
		this.upperMargin = DEFAULT_AXIS_MARGIN;
		this.categoryMargin = DEFAULT_CATEGORY_MARGIN;
		this.maximumCategoryLabelLines = 1;
		this.maximumCategoryLabelWidthRatio = 0.0f;

		this.categoryLabelPositionOffset = 4;
		this.categoryLabelPositions = CategoryLabelPositions.UP_45;
		this.tickLabelFontMap = new HashMap();
		this.tickLabelPaintMap = new HashMap();
		this.categoryLabelToolTips = new HashMap();

	}

	/**
	 * Returns the lower margin for the axis.
	 * 
	 * @return The margin.
	 * 
	 * @see #getUpperMargin()
	 * @see #setLowerMargin(double)
	 */
	public double getLowerMargin() {
		return this.lowerMargin;
	}

	/**
	 * Sets the lower margin for the axis and sends an {@link AxisChangeEvent}
	 * to all registered listeners.
	 * 
	 * @param margin
	 *            the margin as a percentage of the axis length (for example,
	 *            0.05 is five percent).
	 * 
	 * @see #getLowerMargin()
	 */
	public void setLowerMargin(double margin) {
		this.lowerMargin = margin;
	}

	/**
	 * Returns the upper margin for the axis.
	 * 
	 * @return The margin.
	 * 
	 * @see #getLowerMargin()
	 * @see #setUpperMargin(double)
	 */
	public double getUpperMargin() {
		return this.upperMargin;
	}

	/**
	 * Sets the upper margin for the axis and sends an {@link AxisChangeEvent}
	 * to all registered listeners.
	 * 
	 * @param margin
	 *            the margin as a percentage of the axis length (for example,
	 *            0.05 is five percent).
	 * 
	 * @see #getUpperMargin()
	 */
	public void setUpperMargin(double margin) {
		this.upperMargin = margin;
	}

	/**
	 * Returns the category margin.
	 * 
	 * @return The margin.
	 * 
	 * @see #setCategoryMargin(double)
	 */
	public double getCategoryMargin() {
		return this.categoryMargin;
	}

	/**
	 * Sets the category margin and sends an {@link AxisChangeEvent} to all
	 * registered listeners. The overall category margin is distributed over N-1
	 * gaps, where N is the number of categories on the axis.
	 * 
	 * @param margin
	 *            the margin as a percentage of the axis length (for example,
	 *            0.05 is five percent).
	 * 
	 * @see #getCategoryMargin()
	 */
	public void setCategoryMargin(double margin) {
		this.categoryMargin = margin;
	}

	/**
	 * Returns the maximum number of lines to use for each category label.
	 * 
	 * @return The maximum number of lines.
	 * 
	 * @see #setMaximumCategoryLabelLines(int)
	 */
	public int getMaximumCategoryLabelLines() {
		return this.maximumCategoryLabelLines;
	}

	/**
	 * Sets the maximum number of lines to use for each category label and sends
	 * an {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param lines
	 *            the maximum number of lines.
	 * 
	 * @see #getMaximumCategoryLabelLines()
	 */
	public void setMaximumCategoryLabelLines(int lines) {
		this.maximumCategoryLabelLines = lines;
	}

	/**
	 * Returns the category label width ratio.
	 * 
	 * @return The ratio.
	 * 
	 * @see #setMaximumCategoryLabelWidthRatio(float)
	 */
	public float getMaximumCategoryLabelWidthRatio() {
		return this.maximumCategoryLabelWidthRatio;
	}

	/**
	 * Sets the maximum category label width ratio and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param ratio
	 *            the ratio.
	 * 
	 * @see #getMaximumCategoryLabelWidthRatio()
	 */
	public void setMaximumCategoryLabelWidthRatio(float ratio) {
		this.maximumCategoryLabelWidthRatio = ratio;
	}

	/**
	 * Returns the offset between the axis and the category labels (before label
	 * positioning is taken into account).
	 * 
	 * @return The offset (in Java2D units).
	 * 
	 * @see #setCategoryLabelPositionOffset(int)
	 */
	public int getCategoryLabelPositionOffset() {
		return this.categoryLabelPositionOffset;
	}

	/**
	 * Sets the offset between the axis and the category labels (before label
	 * positioning is taken into account).
	 * 
	 * @param offset
	 *            the offset (in Java2D units).
	 * 
	 * @see #getCategoryLabelPositionOffset()
	 */
	public void setCategoryLabelPositionOffset(int offset) {
		this.categoryLabelPositionOffset = offset;
	}

	/**
	 * Returns the category label position specification (this contains label
	 * positioning info for all four possible axis locations).
	 * 
	 * @return The positions (never <code>null</code>).
	 * 
	 * @see #setCategoryLabelPositions(CategoryLabelPositions)
	 */
	public CategoryLabelPositions getCategoryLabelPositions() {
		return this.categoryLabelPositions;
	}

	/**
	 * Sets the category label position specification for the axis and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param positions
	 *            the positions (<code>null</code> not permitted).
	 * 
	 * @see #getCategoryLabelPositions()
	 */
	public void setCategoryLabelPositions(CategoryLabelPositions positions) {
		if (positions == null) {
			throw new IllegalArgumentException("Null 'positions' argument.");
		}
		this.categoryLabelPositions = positions;
	}

	/**
	 * Returns the font for the tick label for the given category.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * 
	 * @return The font (never <code>null</code>).
	 * 
	 * @see #setTickLabelFont(Comparable, Font)
	 */
	public Font getTickLabelFont(Comparable category) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		Font result = (Font) this.tickLabelFontMap.get(category);
		// if there is no specific font, use the general one...
		if (result == null) {
			result = getTickLabelFont();
		}
		return result;
	}

	/**
	 * Sets the font for the tick label for the specified category and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * @param font
	 *            the font (<code>null</code> permitted).
	 * 
	 * @see #getTickLabelFont(Comparable)
	 */
	public void setTickLabelFont(Comparable category, Font font) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		if (font == null) {
			this.tickLabelFontMap.remove(category);
		} else {
			this.tickLabelFontMap.put(category, font);
		}
	}

	/**
	 * Returns the paint for the tick label for the given category.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * 
	 * @return The paint (never <code>null</code>).
	 * 
	 * @see #setTickLabelPaint(Paint)
	 */
	public Paint getTickLabelPaint(Comparable category) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		Paint result = (Paint) this.tickLabelPaintMap.get(category);
		// if there is no specific paint, use the general one...
		if (result == null) {
			result = getTickLabelPaint();
		}
		return result;
	}

	/**
	 * Sets the paint for the tick label for the specified category and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * @param paint
	 *            the paint (<code>null</code> permitted).
	 * 
	 * @see #getTickLabelPaint(Comparable)
	 */
	public void setTickLabelPaint(Comparable category, Paint paint) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		if (paint == null) {
			this.tickLabelPaintMap.remove(category);
		} else {
			this.tickLabelPaintMap.put(category, paint);
		}
	}

	/**
	 * Adds a tooltip to the specified category and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param category
	 *            the category (<code>null<code> not permitted).
	 * @param tooltip
	 *            the tooltip text (<code>null</code> permitted).
	 * 
	 * @see #removeCategoryLabelToolTip(Comparable)
	 */
	public void addCategoryLabelToolTip(Comparable category, String tooltip) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		this.categoryLabelToolTips.put(category, tooltip);
	}

	/**
	 * Returns the tool tip text for the label belonging to the specified
	 * category.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * 
	 * @return The tool tip text (possibly <code>null</code>).
	 * 
	 * @see #addCategoryLabelToolTip(Comparable, String)
	 * @see #removeCategoryLabelToolTip(Comparable)
	 */
	public String getCategoryLabelToolTip(Comparable category) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		return (String) this.categoryLabelToolTips.get(category);
	}

	/**
	 * Removes the tooltip for the specified category and sends an
	 * {@link AxisChangeEvent} to all registered listeners.
	 * 
	 * @param category
	 *            the category (<code>null<code> not permitted).
	 * 
	 * @see #addCategoryLabelToolTip(Comparable, String)
	 * @see #clearCategoryLabelToolTips()
	 */
	public void removeCategoryLabelToolTip(Comparable category) {
		if (category == null) {
			throw new IllegalArgumentException("Null 'category' argument.");
		}
		this.categoryLabelToolTips.remove(category);
	}

	/**
	 * Clears the category label tooltips and sends an {@link AxisChangeEvent}
	 * to all registered listeners.
	 * 
	 * @see #addCategoryLabelToolTip(Comparable, String)
	 * @see #removeCategoryLabelToolTip(Comparable)
	 */
	public void clearCategoryLabelToolTips() {
		this.categoryLabelToolTips.clear();
	}

	/**
	 * Returns the Java 2D coordinate for a category.
	 * 
	 * @param anchor
	 *            the anchor point.
	 * @param category
	 *            the category index.
	 * @param categoryCount
	 *            the category count.
	 * @param area
	 *            the data area.
	 * @param edge
	 *            the location of the axis.
	 * 
	 * @return The coordinate.
	 */
	public double getCategoryJava2DCoordinate(CategoryAnchor anchor,
			int category, int categoryCount, Rectangle2D area,
			RectangleEdge edge) {

		double result = 0.0;
		if (anchor == CategoryAnchor.START) {
			result = getCategoryStart(category, categoryCount, area, edge);
		} else if (anchor == CategoryAnchor.MIDDLE) {
			result = getCategoryMiddle(category, categoryCount, area, edge);
		} else if (anchor == CategoryAnchor.END) {
			result = getCategoryEnd(category, categoryCount, area, edge);
		}
		return result;

	}

	/**
	 * Returns the starting coordinate for the specified category.
	 * 
	 * @param category
	 *            the category.
	 * @param categoryCount
	 *            the number of categories.
	 * @param area
	 *            the data area.
	 * @param edge
	 *            the axis location.
	 * 
	 * @return The coordinate.
	 * 
	 * @see #getCategoryMiddle(int, int, Rectangle2D, RectangleEdge)
	 * @see #getCategoryEnd(int, int, Rectangle2D, RectangleEdge)
	 */
	public double getCategoryStart(int category, int categoryCount,
			Rectangle2D area, RectangleEdge edge) {

		double result = 0.0;
		if ((edge == RectangleEdge.TOP) || (edge == RectangleEdge.BOTTOM)) {
			result = area.getX() + area.getWidth() * getLowerMargin();
		} else if ((edge == RectangleEdge.LEFT)
				|| (edge == RectangleEdge.RIGHT)) {
			result = area.getMinY() + area.getHeight() * getLowerMargin();
		}

		double categorySize = calculateCategorySize(categoryCount, area, edge);
		double categoryGapWidth = calculateCategoryGapSize(categoryCount, area,
				edge);

		result = result + category * (categorySize + categoryGapWidth);
		return result;

	}

	/**
	 * Returns the middle coordinate for the specified category.
	 * 
	 * @param category
	 *            the category.
	 * @param categoryCount
	 *            the number of categories.
	 * @param area
	 *            the data area.
	 * @param edge
	 *            the axis location.
	 * 
	 * @return The coordinate.
	 * 
	 * @see #getCategoryStart(int, int, Rectangle2D, RectangleEdge)
	 * @see #getCategoryEnd(int, int, Rectangle2D, RectangleEdge)
	 */
	public double getCategoryMiddle(int category, int categoryCount,
			Rectangle2D area, RectangleEdge edge) {

		if (category < 0 || category >= categoryCount) {
			throw new IllegalArgumentException("Invalid category index: "
					+ category);
		}
		return getCategoryStart(category, categoryCount, area, edge)
				+ calculateCategorySize(categoryCount, area, edge) / 2;

	}

	/**
	 * Returns the end coordinate for the specified category.
	 * 
	 * @param category
	 *            the category.
	 * @param categoryCount
	 *            the number of categories.
	 * @param area
	 *            the data area.
	 * @param edge
	 *            the axis location.
	 * 
	 * @return The coordinate.
	 * 
	 * @see #getCategoryStart(int, int, Rectangle2D, RectangleEdge)
	 * @see #getCategoryMiddle(int, int, Rectangle2D, RectangleEdge)
	 */
	public double getCategoryEnd(int category, int categoryCount,
			Rectangle2D area, RectangleEdge edge) {

		return getCategoryStart(category, categoryCount, area, edge)
				+ calculateCategorySize(categoryCount, area, edge);

	}

	/**
	 * A convenience method that returns the axis coordinate for the centre of a
	 * category.
	 * 
	 * @param category
	 *            the category key (<code>null</code> not permitted).
	 * @param categories
	 *            the categories (<code>null</code> not permitted).
	 * @param area
	 *            the data area (<code>null</code> not permitted).
	 * @param edge
	 *            the edge along which the axis lies (<code>null</code> not
	 *            permitted).
	 * 
	 * @return The centre coordinate.
	 * 
	 * @since 1.0.11
	 * 
	 * @see #getCategorySeriesMiddle(Comparable, Comparable, CategoryDataset,
	 *      double, Rectangle2D, RectangleEdge)
	 */
	public double getCategoryMiddle(Comparable category, List categories,
			Rectangle2D area, RectangleEdge edge) {
		if (categories == null) {
			throw new IllegalArgumentException("Null 'categories' argument.");
		}
		int categoryIndex = categories.indexOf(category);
		int categoryCount = categories.size();
		return getCategoryMiddle(categoryIndex, categoryCount, area, edge);
	}

	/**
	 * Returns the middle coordinate (in Java2D space) for a series within a
	 * category.
	 * 
	 * @param category
	 *            the category (<code>null</code> not permitted).
	 * @param seriesKey
	 *            the series key (<code>null</code> not permitted).
	 * @param dataset
	 *            the dataset (<code>null</code> not permitted).
	 * @param itemMargin
	 *            the item margin (0.0 <= itemMargin < 1.0);
	 * @param area
	 *            the area (<code>null</code> not permitted).
	 * @param edge
	 *            the edge (<code>null</code> not permitted).
	 * 
	 * @return The coordinate in Java2D space.
	 * 
	 * @since 1.0.7
	 */
	public double getCategorySeriesMiddle(Comparable category,
			Comparable seriesKey, CategoryDataset dataset, double itemMargin,
			Rectangle2D area, RectangleEdge edge) {

		int categoryIndex = dataset.getColumnIndex(category);
		int categoryCount = dataset.getColumnCount();
		int seriesIndex = dataset.getRowIndex(seriesKey);
		int seriesCount = dataset.getRowCount();
		double start = getCategoryStart(categoryIndex, categoryCount, area,
				edge);
		double end = getCategoryEnd(categoryIndex, categoryCount, area, edge);
		double width = end - start;
		if (seriesCount == 1) {
			return start + width / 2.0;
		} else {
			double gap = (width * itemMargin) / (seriesCount - 1);
			double ww = (width * (1 - itemMargin)) / seriesCount;
			return start + (seriesIndex * (ww + gap)) + ww / 2.0;
		}
	}

	/**
	 * Returns the middle coordinate (in Java2D space) for a series within a
	 * category.
	 * 
	 * @param categoryIndex
	 *            the category index.
	 * @param categoryCount
	 *            the category count.
	 * @param seriesIndex
	 *            the series index.
	 * @param seriesCount
	 *            the series count.
	 * @param itemMargin
	 *            the item margin (0.0 <= itemMargin < 1.0);
	 * @param area
	 *            the area (<code>null</code> not permitted).
	 * @param edge
	 *            the edge (<code>null</code> not permitted).
	 * 
	 * @return The coordinate in Java2D space.
	 * 
	 * @since 1.0.13
	 */
	public double getCategorySeriesMiddle(int categoryIndex, int categoryCount,
			int seriesIndex, int seriesCount, double itemMargin,
			Rectangle2D area, RectangleEdge edge) {

		double start = getCategoryStart(categoryIndex, categoryCount, area,
				edge);
		double end = getCategoryEnd(categoryIndex, categoryCount, area, edge);
		double width = end - start;
		if (seriesCount == 1) {
			return start + width / 2.0;
		} else {
			double gap = (width * itemMargin) / (seriesCount - 1);
			double ww = (width * (1 - itemMargin)) / seriesCount;
			return start + (seriesIndex * (ww + gap)) + ww / 2.0;
		}
	}

	/**
	 * Calculates the size (width or height, depending on the location of the
	 * axis) of a category.
	 * 
	 * @param categoryCount
	 *            the number of categories.
	 * @param area
	 *            the area within which the categories will be drawn.
	 * @param edge
	 *            the axis location.
	 * 
	 * @return The category size.
	 */
	protected double calculateCategorySize(int categoryCount, Rectangle2D area,
			RectangleEdge edge) {

		double result = 0.0;
		double available = 0.0;

		if ((edge == RectangleEdge.TOP) || (edge == RectangleEdge.BOTTOM)) {
			available = area.getWidth();
		} else if ((edge == RectangleEdge.LEFT)
				|| (edge == RectangleEdge.RIGHT)) {
			available = area.getHeight();
		}
		if (categoryCount > 1) {
			result = available
					* (1 - getLowerMargin() - getUpperMargin() - getCategoryMargin());
			result = result / categoryCount;
		} else {
			result = available * (1 - getLowerMargin() - getUpperMargin());
		}
		return result;

	}

	/**
	 * Calculates the size (width or height, depending on the location of the
	 * axis) of a category gap.
	 * 
	 * @param categoryCount
	 *            the number of categories.
	 * @param area
	 *            the area within which the categories will be drawn.
	 * @param edge
	 *            the axis location.
	 * 
	 * @return The category gap width.
	 */
	protected double calculateCategoryGapSize(int categoryCount,
			Rectangle2D area, RectangleEdge edge) {

		double result = 0.0;
		double available = 0.0;

		if ((edge == RectangleEdge.TOP) || (edge == RectangleEdge.BOTTOM)) {
			available = area.getWidth();
		} else if ((edge == RectangleEdge.LEFT)
				|| (edge == RectangleEdge.RIGHT)) {
			available = area.getHeight();
		}

		if (categoryCount > 1) {
			result = available * getCategoryMargin() / (categoryCount - 1);
		}

		return result;

	}

	/**
	 * Estimates the space required for the axis, given a specific drawing area.
	 * 
	 * @param g2
	 *            the graphics device (used to obtain font information).
	 * @param plot
	 *            the plot that the axis belongs to.
	 * @param plotArea
	 *            the area within which the axis should be drawn.
	 * @param edge
	 *            the axis location (top or bottom).
	 * @param space
	 *            the space already reserved.
	 * 
	 * @return The space required to draw the axis.
	 */
	public AxisSpace reserveSpace(Canvas g2, Plot plot, Rectangle2D plotArea,
			RectangleEdge edge, AxisSpace space) {

		// create a new space object if one wasn't supplied...
		if (space == null) {
			space = new AxisSpace();
		}

		// if the axis is not visible, no additional space is required...
		if (!isVisible()) {
			return space;
		}

		// calculate the max size of the tick labels (if visible)...
		double tickLabelHeight = 0.0;
		double tickLabelWidth = 0.0;
		if (isTickLabelsVisible()) {
			// g2.setFont(getTickLabelFont());
			AxisState state = new AxisState();
			// we call refresh ticks just to get the maximum width or height
			refreshTicks(g2, state, plotArea, edge);
			if (edge == RectangleEdge.TOP) {
				tickLabelHeight = state.getMax();
			} else if (edge == RectangleEdge.BOTTOM) {
				tickLabelHeight = state.getMax();
			} else if (edge == RectangleEdge.LEFT) {
				tickLabelWidth = state.getMax();
			} else if (edge == RectangleEdge.RIGHT) {
				tickLabelWidth = state.getMax();
			}
		}

		// get the axis label size and update the space object...
		Rectangle2D labelEnclosure = getLabelEnclosure(g2, edge);
		double labelHeight = 0.0;
		double labelWidth = 0.0;
		if (RectangleEdge.isTopOrBottom(edge)) {
			labelHeight = labelEnclosure.getHeight();
			space.add(labelHeight + tickLabelHeight
					+ this.categoryLabelPositionOffset, edge);
		} else if (RectangleEdge.isLeftOrRight(edge)) {
			labelWidth = labelEnclosure.getWidth();
			space.add(labelWidth + tickLabelWidth
					+ this.categoryLabelPositionOffset, edge);
		}
		return space;

	}

	/**
	 * Configures the axis against the current plot.
	 */
	public void configure() {
		// nothing required
	}

	/**
	 * Draws the axis on a Java 2D graphics device (such as the screen or a
	 * printer).
	 * 
	 * @param g2
	 *            the graphics device (<code>null</code> not permitted).
	 * @param cursor
	 *            the cursor location.
	 * @param plotArea
	 *            the area within which the axis should be drawn (
	 *            <code>null</code> not permitted).
	 * @param dataArea
	 *            the area within which the plot is being drawn (
	 *            <code>null</code> not permitted).
	 * @param edge
	 *            the location of the axis (<code>null</code> not permitted).
	 * @param plotState
	 *            collects information about the plot (<code>null</code>
	 *            permitted).
	 * 
	 * @return The axis state (never <code>null</code>).
	 */
	public AxisState draw(Canvas g2, double cursor, Rectangle2D plotArea,
			Rectangle2D dataArea, RectangleEdge edge,
			PlotRenderingInfo plotState) {

		// if the axis is not visible, don't draw it...
		if (!isVisible()) {
			return new AxisState(cursor);
		}

		if (isAxisLineVisible()) {
			drawAxisLine(g2, cursor, dataArea, edge);
		}
		AxisState state = new AxisState(cursor);
		if (isTickMarksVisible()) {
			drawTickMarks(g2, cursor, dataArea, edge, state);
		}

		// draw the category labels and axis label
		state = drawCategoryLabels(g2, plotArea, dataArea, edge, state,
				plotState);
		state = drawLabel(getLabel(), g2, plotArea, dataArea, edge, state);
		createAndAddEntity(cursor, state, dataArea, edge, plotState);
		return state;

	}

	/**
	 * Draws the category labels and returns the updated axis state.
	 * 
	 * @param g2
	 *            the graphics device (<code>null</code> not permitted).
	 * @param dataArea
	 *            the area inside the axes (<code>null</code> not permitted).
	 * @param edge
	 *            the axis location (<code>null</code> not permitted).
	 * @param state
	 *            the axis state (<code>null</code> not permitted).
	 * @param plotState
	 *            collects information about the plot (<code>null</code>
	 *            permitted).
	 * 
	 * @return The updated axis state (never <code>null</code>).
	 * 
	 * @deprecated Use
	 *             {@link #drawCategoryLabels(Graphics2D, Rectangle2D, Rectangle2D, RectangleEdge, AxisState, PlotRenderingInfo)}
	 *             .
	 */
	protected AxisState drawCategoryLabels(Canvas g2, Rectangle2D dataArea,
			RectangleEdge edge, AxisState state, PlotRenderingInfo plotState) {

		// this method is deprecated because we really need the plotArea
		// when drawing the labels - see bug 1277726
		return drawCategoryLabels(g2, dataArea, dataArea, edge, state,
				plotState);
	}

	/**
	 * Draws the category labels and returns the updated axis state.
	 * 
	 * @param g2
	 *            the graphics device (<code>null</code> not permitted).
	 * @param plotArea
	 *            the plot area (<code>null</code> not permitted).
	 * @param dataArea
	 *            the area inside the axes (<code>null</code> not permitted).
	 * @param edge
	 *            the axis location (<code>null</code> not permitted).
	 * @param state
	 *            the axis state (<code>null</code> not permitted).
	 * @param plotState
	 *            collects information about the plot (<code>null</code>
	 *            permitted).
	 * 
	 * @return The updated axis state (never <code>null</code>).
	 */
	protected AxisState drawCategoryLabels(Canvas g2, Rectangle2D plotArea,
			Rectangle2D dataArea, RectangleEdge edge, AxisState state,
			PlotRenderingInfo plotState) {

		if (state == null) {
			throw new IllegalArgumentException("Null 'state' argument.");
		}

		if (isTickLabelsVisible()) {
			List ticks = refreshTicks(g2, state, plotArea, edge);
			state.setTicks(ticks);

			int categoryIndex = 0;
			Iterator iterator = ticks.iterator();
			while (iterator.hasNext()) {

				CategoryTick tick = (CategoryTick) iterator.next();
				Font tickLabelFont = getTickLabelFont(tick.getCategory());

				Paint paint = getTickLabelPaint(tick.getCategory());
				paint.setTypeface(tickLabelFont.getTypeFace());
				paint.setTextSize(tickLabelFont.getSize());
				CategoryLabelPosition position = this.categoryLabelPositions
						.getLabelPosition(edge);
				double x0 = 0.0;
				double x1 = 0.0;
				double y0 = 0.0;
				double y1 = 0.0;
				if (edge == RectangleEdge.TOP) {
					x0 = getCategoryStart(categoryIndex, ticks.size(),
							dataArea, edge);
					x1 = getCategoryEnd(categoryIndex, ticks.size(), dataArea,
							edge);
					y1 = state.getCursor() - this.categoryLabelPositionOffset;
					y0 = y1 - state.getMax();
				} else if (edge == RectangleEdge.BOTTOM) {
					x0 = getCategoryStart(categoryIndex, ticks.size(),
							dataArea, edge);
					x1 = getCategoryEnd(categoryIndex, ticks.size(), dataArea,
							edge);
					y0 = state.getCursor() + this.categoryLabelPositionOffset;
					y1 = y0 + state.getMax();
				} else if (edge == RectangleEdge.LEFT) {
					y0 = getCategoryStart(categoryIndex, ticks.size(),
							dataArea, edge);
					y1 = getCategoryEnd(categoryIndex, ticks.size(), dataArea,
							edge);
					x1 = state.getCursor() - this.categoryLabelPositionOffset;
					x0 = x1 - state.getMax();
				} else if (edge == RectangleEdge.RIGHT) {
					y0 = getCategoryStart(categoryIndex, ticks.size(),
							dataArea, edge);
					y1 = getCategoryEnd(categoryIndex, ticks.size(), dataArea,
							edge);
					x0 = state.getCursor() + this.categoryLabelPositionOffset;
					x1 = x0 - state.getMax();
				}
				Rectangle2D area = new Rectangle2D.Double(x0, y0, (x1 - x0),
						(y1 - y0));
				Point2D anchorPoint = RectangleAnchor.coordinates(area,
						position.getCategoryAnchor());
				TextBlock block = tick.getLabel();
				block.draw(g2, (float) anchorPoint.getX(), (float) anchorPoint
						.getY(), position.getLabelAnchor(), (float) anchorPoint
						.getX(), (float) anchorPoint.getY(), position
						.getAngle(), paint);
				Shape bounds = block.calculateBounds(g2, (float) anchorPoint
						.getX(), (float) anchorPoint.getY(), position
						.getLabelAnchor(), (float) anchorPoint.getX(),
						(float) anchorPoint.getY(), position.getAngle());
				if (plotState != null && plotState.getOwner() != null) {
					EntityCollection entities = plotState.getOwner()
							.getEntityCollection();
					if (entities != null) {
						String tooltip = getCategoryLabelToolTip(tick
								.getCategory());
						entities.add(new CategoryLabelEntity(
								tick.getCategory(), bounds, tooltip, null));
					}
				}
				categoryIndex++;
			}

			if (edge.equals(RectangleEdge.TOP)) {
				double h = state.getMax() + this.categoryLabelPositionOffset;
				state.cursorUp(h);
			} else if (edge.equals(RectangleEdge.BOTTOM)) {
				double h = state.getMax() + this.categoryLabelPositionOffset;
				state.cursorDown(h);
			} else if (edge == RectangleEdge.LEFT) {
				double w = state.getMax() + this.categoryLabelPositionOffset;
				state.cursorLeft(w);
			} else if (edge == RectangleEdge.RIGHT) {
				double w = state.getMax() + this.categoryLabelPositionOffset;
				state.cursorRight(w);
			}
		}
		return state;
	}

	/**
	 * Creates a temporary list of ticks that can be used when drawing the axis.
	 * 
	 * @param g2
	 *            the graphics device (used to get font measurements).
	 * @param state
	 *            the axis state.
	 * @param dataArea
	 *            the area inside the axes.
	 * @param edge
	 *            the location of the axis.
	 * 
	 * @return A list of ticks.
	 */
	public List refreshTicks(Canvas g2, AxisState state, Rectangle2D dataArea,
			RectangleEdge edge) {

		List ticks = new java.util.ArrayList();

		// sanity check for data area...
		if (dataArea.getHeight() <= 0.0 || dataArea.getWidth() < 0.0) {
			return ticks;
		}

		CategoryPlot plot = (CategoryPlot) getPlot();
		List categories = plot.getCategoriesForAxis(this);
		double max = 0.0;

		if (categories != null) {
			CategoryLabelPosition position = this.categoryLabelPositions
					.getLabelPosition(edge);
			float r = this.maximumCategoryLabelWidthRatio;
			if (r <= 0.0) {
				r = position.getWidthRatio();
			}

			float l = 0.0f;
			if (position.getWidthType() == CategoryLabelWidthType.CATEGORY) {
				l = (float) calculateCategorySize(categories.size(), dataArea,
						edge);
			} else {
				if (RectangleEdge.isLeftOrRight(edge)) {
					l = (float) dataArea.getWidth();
				} else {
					l = (float) dataArea.getHeight();
				}
			}
			int categoryIndex = 0;
			Iterator iterator = categories.iterator();
			while (iterator.hasNext()) {
				Comparable category = (Comparable) iterator.next();
				// g2.setFont(getTickLabelFont(category));
				TextBlock label = createLabel(category, l * r, edge, g2);
				if (edge == RectangleEdge.TOP || edge == RectangleEdge.BOTTOM) {
					max = Math.max(max, calculateTextBlockHeight(label,
							position, g2));
				} else if (edge == RectangleEdge.LEFT
						|| edge == RectangleEdge.RIGHT) {
					max = Math.max(max, calculateTextBlockWidth(label,
							position, g2));
				}
				Tick tick = new CategoryTick(category, label, position
						.getLabelAnchor(), position.getRotationAnchor(),
						position.getAngle());
				ticks.add(tick);
				categoryIndex = categoryIndex + 1;
			}
		}
		state.setMax(max);
		return ticks;

	}

	/**
	 * Draws the tick marks.
	 * 
	 * @since 1.0.13
	 */
	public void drawTickMarks(Canvas g2, double cursor, Rectangle2D dataArea,
			RectangleEdge edge, AxisState state) {

		Plot p = getPlot();
		if (p == null) {
			return;
		}
		CategoryPlot plot = (CategoryPlot) p;
		double il = getTickMarkInsideLength();
		double ol = getTickMarkOutsideLength();
		Line2D line = new Line2D.Double();
		List categories = plot.getCategoriesForAxis(this);

		Paint tickMark = getTickMarkPaint();
		int tickMarkStroke = getTickMarkStroke();
		tickMark.setStyle(Paint.Style.STROKE);
		tickMark.setStrokeWidth(tickMarkStroke);

		if (edge.equals(RectangleEdge.TOP)) {
			Iterator iterator = categories.iterator();
			while (iterator.hasNext()) {
				Comparable key = (Comparable) iterator.next();
				double x = getCategoryMiddle(key, categories, dataArea, edge);
				line.setLine(x, cursor, x, cursor + il);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);

				line.setLine(x, cursor, x, cursor - ol);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
			}
			state.cursorUp(ol);
		} else if (edge.equals(RectangleEdge.BOTTOM)) {
			Iterator iterator = categories.iterator();
			while (iterator.hasNext()) {
				Comparable key = (Comparable) iterator.next();
				double x = getCategoryMiddle(key, categories, dataArea, edge);
				line.setLine(x, cursor, x, cursor - il);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
				line.setLine(x, cursor, x, cursor + ol);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
			}
			state.cursorDown(ol);
		} else if (edge.equals(RectangleEdge.LEFT)) {
			Iterator iterator = categories.iterator();
			while (iterator.hasNext()) {
				Comparable key = (Comparable) iterator.next();
				double y = getCategoryMiddle(key, categories, dataArea, edge);
				line.setLine(cursor, y, cursor + il, y);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
				line.setLine(cursor, y, cursor - ol, y);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
			}
			state.cursorLeft(ol);
		} else if (edge.equals(RectangleEdge.RIGHT)) {
			Iterator iterator = categories.iterator();
			while (iterator.hasNext()) {
				Comparable key = (Comparable) iterator.next();
				double y = getCategoryMiddle(key, categories, dataArea, edge);
				line.setLine(cursor, y, cursor - il, y);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
				line.setLine(cursor, y, cursor + ol, y);
				g2.drawLine((float) line.getX1(), (float) line.getY1(),
						(float) line.getX2(), (float) line.getY2(), tickMark);
			}
			state.cursorRight(ol);
		}
	}

	/**
	 * Creates a label.
	 * 
	 * @param category
	 *            the category.
	 * @param width
	 *            the available width.
	 * @param edge
	 *            the edge on which the axis appears.
	 * @param g2
	 *            the graphics device.
	 * 
	 * @return A label.
	 */
	protected TextBlock createLabel(Comparable category, float width,
			RectangleEdge edge, Canvas g2) {
		TextBlock label = TextUtilities.createTextBlock(category.toString(),
				getTickLabelFont(category), getTickLabelPaint(category), width,
				this.maximumCategoryLabelLines, new G2TextMeasurer(
						getLabelPaint()));
		return label;
	}

	/**
	 * A utility method for determining the width of a text block.
	 * 
	 * @param block
	 *            the text block.
	 * @param position
	 *            the position.
	 * @param g2
	 *            the graphics device.
	 * 
	 * @return The width.
	 */
	protected double calculateTextBlockWidth(TextBlock block,
			CategoryLabelPosition position, Canvas g2) {

		RectangleInsets insets = getTickLabelInsets();
		Size2D size = block.calculateDimensions(g2);
		Rectangle2D box = new Rectangle2D.Double(0.0, 0.0, size.getWidth(),
				size.getHeight());
		Shape rotatedBox = ShapeUtilities.rotateShape(box, position.getAngle(),
				0.0f, 0.0f);
		double w = rotatedBox.getBounds2D().getWidth() + insets.getLeft()
				+ insets.getRight();
		return w;

	}

	/**
	 * A utility method for determining the height of a text block.
	 * 
	 * @param block
	 *            the text block.
	 * @param position
	 *            the label position.
	 * @param g2
	 *            the graphics device.
	 * 
	 * @return The height.
	 */
	protected double calculateTextBlockHeight(TextBlock block,
			CategoryLabelPosition position, Canvas g2) {

		RectangleInsets insets = getTickLabelInsets();
		Size2D size = block.calculateDimensions(g2);
		Rectangle2D box = new Rectangle2D.Double(0.0, 0.0, size.getWidth(),
				size.getHeight());
		Shape rotatedBox = ShapeUtilities.rotateShape(box, position.getAngle(),
				0.0f, 0.0f);
		double h = rotatedBox.getBounds2D().getHeight() + insets.getTop()
				+ insets.getBottom();
		return h;

	}

}
